Linking Entities

Introduction

In real-world applications, entities rarely exist in isolation.
To model business domains properly, you need to express relationships between your data tables.

In yeet, this is done via linked properties.
A linked property connects one entity to another and defines how records relate to each other (e.g. one customer → many orders).

Every relationship relies on at least one uniquely identifiable side (typically a primary key) so that each link can be resolved unambiguously.

What is a linked property?

A linked property is a special property on an entity that:

• points to another entity (the target),
• references a key or unique field of that target,
• defines the cardinality of the relationship (1:1, 1:n, …).

You use linked properties to:

• navigate between related entities (e.g. from an order to its customer),
• avoid data duplication (store data once, link it where needed),
• enforce consistent relationships across your data model.

1:1 relationships

A 1:1 relationship means that one record of entity A is linked to at most one record of entity B – and vice versa.

In yeet this typically means:

• entity A has a linked property that points to the key of entity B, and
• the linking property (or the target key) is unique, so each link refers to at most one record.

Typical use cases:

• splitting rarely used or sensitive data into a separate entity
  (e.g. User ↔ UserProfile),
• attaching “extension” data to a core record without adding many optional columns.

Example

• User has a linked property Profile → UserProfile
• each UserProfile belongs to exactly one User.

1:n relationships

A 1:n (one-to-many) relationship means:

• one record of entity A can be linked to many records of entity B, and
• each record of entity B is linked to one record of entity A.

In yeet this is usually modeled by:

• a linked property on the “many” side that points to the key of the “one” side.

Typical example:

• Order (one) ↔ OrderItem (many)
  One order can have multiple items; each order item refers to exactly one order.

Example

• OrderItem has a linked property Order → Order
• you can navigate from an Order to all related OrderItems.

Modelling guidelines

When designing linked properties in yeet, keep the following in mind:

• Uniqueness & keys
  Ensure that the target of a link is uniquely identifiable (primary key or unique field).
  Ambiguous keys make relationships hard to reason about.

• Navigation direction
  Decide from which side you primarily want to navigate:

  • from the “one” side (e.g. Customer → all Orders),
  • or from the “many” side (e.g. Order → its Customer).

• Cardinality changes
  Requirements evolve. A 1:1 or 1:n relationship today may need to become n:m later.
  Introducing a link entity early can make future changes easier.

• Data integrity
  Whenever possible, use linked properties instead of duplicating data in multiple entities. This keeps your data model consistent and reduces the risk of conflicting information.